Examples of Subroutines With Labeled Parameters

This section provides examples of subroutine definitions with labeled parameters and of calls to those subroutines.

The following subroutine returns the area of a circle based on its radius:



 
on areaOfCircle from radius

    -- Make sure the parameter is a real number or an integer.

    if class of radius is contained by {integer, real}

        return radius * pi  -- pi is predefined by AppleScript.

    else

        error "The parameter must be a real number or an integer."

    end if

end areaOfCircle



-- To call areaOfCircle:

areaOfCircle from 7 --result: 21.991148575129

The following subroutine searches for a specific string in a list of files. It returns a list containing the names of any files that contained the specified string. For the searchFiles handler to work, the specified files must be on the startup disk (the current system disk, obtained from the Finder).



 
to searchFiles of filesToSearch for theString

    -- filesToSearch: list of AppleWorks files.

    -- theString: the string to be searched for.

    -- Note: always searches on startup disk.

    set hits to {}

    tell application "Finder" to set theDisk to (startup disk as string)

    tell application "AppleWorks"

        repeat with i from 1 to (count items of filesToSearch)

            set currentWindow to item i of filesToSearch

            set currentFile to theDisk & currentWindow

            open currentFile

            set docText to text body of front document

            if docText contains theString then

                -- Append currentWindow to list of hits.

                set hits to hits & currentWindow

            end if

            close front document saving no

        end repeat

        return hits

    end tell -- application "AppleWorks"

end searchFiles



-- To call searchFiles:

searchFiles of {"March Expenses", "April Expenses", ¬

    "May Expenses", "June Expenses"} for "LeChateau"

--result: {"March Expenses", "May Expenses"} (if those two

--          documents contain the phrase "LeChateau")

The following subroutine uses the special label given to define a parameter with the label rounding . By using verb forms ending with "ing" as labels, you can often make subroutine calls easier to read.



 
to findNumbers of numberList above minLimit ¬

    given rounding:roundBoolean

        set resultList to {}

        repeat with i from 1 to (count items of numberList)

            set x to item i of numberList

            if roundBoolean = true then

                -- Use copy so original list isn't modified.

                copy (x + 0.5) div 1 to x

            end if

            if x > minLimit then

                copy resultList & x to resultList

            end if

        end repeat

        return resultList

end findNumbers



-- To call findNumbers:



--  where myList is thelist of numbers {2, 5, 19.75, 99, 1}:

findNumbers of myList above 19 given rounding:true 

    --result: {20, 99}

findNumbers of myList above 19 given rounding:false

    --result: {19.75, 99}



findNumbers of {5.1, 20.1, 20.5, 33} above 20 given rounding:true

    --result: {21, 33}



findNumbers of {5.1, 20.1, 20.5, 33.7} above 20 given rounding:false

    --result: {20.1, 20.5, 33.7}

Another way to call the findNumbers subroutine is to use a With or Without clause to specify the value of the rounding parameter. A With or Without clause specifies whether a parameter's value is true or false . (In fact, when you compile the previous examples, AppleScript automatically converts given rounding:true to with rounding and given rounding:false to without rounding .) So the following statements are equivalent to the last two statements in the previous example and generate the same results.



 
findNumbers of {5.1, 20.1, 20.5, 33} above 20 with rounding

    --result: {21, 33}



findNumbers of {5.1, 20.1, 20.5, 33.7} above 20 without rounding

    --result: {20.1, 20.5, 33.7}

The subroutine parameter labels that can be used without the special label given allow you considerable flexibility in defining handlers that sound English-like. For example, here's a routine that takes any parameter that can be displayed as a string and displays it in a dialog box:



 
on rock around the clock

    display dialog (clock as string)

end rock

The statement



 
rock around the current date

later in the same script displays the current date in a dialog box.

Here's another example of the use of subroutine parameter labels:



 
to check for yourNumber from bottom thru top

    if bottom  yourNumber and yourNumber  top then

        display dialog "Congratulations! You scored."

    end if

end check

The statement



 
check for 8 from 7 thru 10

later in the same script displays the specified dialog box.